ArangoDB with Python: Database Management Essentials (Setup, Users, Backup, Restore)

# Pull the ArangoDB image
# For users in mainland China, consider using registry mirrors for faster downloads.
# Refer to a guide on accelerating Docker pulls in China if needed. (e.g., 国内镜像源)
docker pull arangodb/arangodb

# Create a user-defined network for ArangoDB and potentially other related containers
docker network create my_arangodb_network

# Run the ArangoDB container with data persistence and on the user-defined network
# A named volume ('arangodb_data' in this example) is managed by Docker
# and is the preferred way for database persistence in development/testing.
# The data inside the container's /var/lib/arangodb3 directory will be stored in this volume.

# IMPORTANT: The -e ARANGO_ROOT_PASSWORD sets the INITIAL password for the 'root' user
# in the '_system' database. This user has administrative privileges required for
# tasks like creating other databases and users. Remember this password!

# docker run options:
# -d: Run the container in detached mode (in the background)
# --name arangodb_instance: Assign a memorable name to the container
# --network my_arangodb_network: Connect the container to the user-defined network
# --network-alias arangodb_alias: Assign a network alias accessible from other containers on the same network
# -e ARANGO_ROOT_PASSWORD='your-secret-password': Set the root password (REQUIRED!) - REPLACE WITH A SECURE PASSWORD
# -p 8529:8529: Map host port 8529 to container port 8529 (ArangoDB's default) - Allows access from the host machine
# -v arangodb_data:/var/lib/arangodb3: Mount the named volume 'arangodb_data' to the data directory inside the container
docker run -d \
  --name arangodb_instance \
  --network my_arangodb_network \
  --network-alias arangodb_alias \
  -e ARANGO_ROOT_PASSWORD='your-secret-password' \
  -p 8529:8529 \
  -v arangodb_data:/var/lib/arangodb3 \
  arangodb/arangodb

# After running, wait a moment for ArangoDB to start up inside the container.
# You can check logs with: docker logs arangodb_instance

# To verify the volume was created:
# docker volume ls

# To inspect the network (optional):
# docker network inspect my_arangodb_network

# To stop the container later:
# docker stop arangodb_instance

# To start the container again (data will be loaded from the volume):
# docker start arangodb_instance

# To remove the container (volume data remains unless explicitly removed with docker volume rm):
# docker rm arangodb_instance

# To remove the volume and data (only do this if you no longer need the data and are SURE!):
# docker volume rm arangodb_data

# To remove the user-defined network (only if no containers are attached):
# docker network rm my_arangodb_network

pip install python-arango

from arango import ArangoClient

# Initialize the client connected to your ArangoDB instance
# We are connecting from the host machine, so use localhost and the mapped port
client = ArangoClient(hosts='http://localhost:8529')

# Replace 'your_secret_password' with the actual root password used during docker run
root_password_for_management = 'your_secret_password'

print("\nAttempting to connect to _system database for management tasks...")
try:
    # Connect as root or another user with sufficient management privileges
    # The '_system' database is where global settings and users reside.
    sys_db = client.db('_system', username='root', password=root_password_for_management)
    print("Connected to _system database.")

    # User management methods are accessed via client.users
    user_manager = client.users
    print("User management operations available via client.users.")

except Exception as e:
    print(f"Failed to connect to _system for management. Ensure ArangoDB is running and root password is correct: {e}")

# The 'sys_db' object can also be used for database-level operations within _system,
# but creating/dropping databases and managing users often uses methods directly on the 'client' or 'client.users'.

# Ensure user_manager object exists from the connection step
if 'user_manager' in locals() and user_manager:
    print("\nListing all Users:")
    try:
        users = user_manager.all()
        for user in users:
            # User object structure might vary slightly by version, common keys: 'username', 'active'
            # Access dictionary keys safely using .get()
            print(f"- Username: {user.get('username', 'N/A')}, Active: {user.get('active', 'N/A')}")
    except Exception as e:
        print(f"Failed to list users: {e}")
else:
    print("\nNot connected to _system with sufficient privileges to list users.")

# Ensure client object is available and connection to _system is possible (implied by user_manager working)
if 'client' in locals() and client and 'user_manager' in locals() and user_manager:
    # Define the name for your application database and the new user credentials
    app_database_name = 'your_application_db' # REPLACE with your desired database name
    app_username = 'your_app_user'         # REPLACE with your desired username
    app_password = 'a_secure_password'     # REPLACE with a strong, secure password for the app user

    # --- Step 3a: Create the application database if it doesn't exist ---
    print(f"\nAttempting to create database '{app_database_name}' if it doesn't exist...")
    try:
        if not client.has_database(app_database_name):
            # create_database requires connection to _system with sufficient privileges (like root)
             # It can be called directly on the client object initialized with admin credentials to _system
            client.create_database(app_database_name)
            print(f"Database '{app_database_name}' created.")
        else:
            print(f"Database '{app_database_name}' already exists.")

    except Exception as e:
        print(f"Failed to create database '{app_database_name}'. Check root connection/privileges/name: {e}")
        # If database creation fails, subsequent steps might also fail.

    # --- Step 3b: Create the application user ---
    # Recommended: Check if user exists before attempting creation to avoid errors.
    print(f"\nAttempting to create user '{app_username}'...")
    try:
        if not user_manager.has(app_username):
            # create_user requires connection with sufficient privileges (e.g., root to _system)
            # 'databases' parameter grants initial access. Access levels: 'rw', 'ro', ''
            user_manager.create_user(
                app_username,
                app_password,
                active=True,
                databases={app_database_name: 'rw'} # Grant read/write access to YOUR application database
            )
            print(f"User '{app_username}' created and granted 'rw' access to '{app_database_name}'.")
            # After this, your application code can use username=app_username, password=app_password
            # to connect to client.db(app_database_name, ...) for data operations.
        else:
            print(f"User '{app_username}' already exists. Skipping creation.")
            # If user exists, you might want to update their password or permissions instead.
            # See the update_user example below.

    except Exception as e:
        print(f"Failed to create user '{app_username}': {e}")

else:
    print("\nNot connected with sufficient privileges to create databases/users.")

# Ensure user_manager object exists
if 'user_manager' in locals() and user_manager:
    user_to_update = 'your_app_user' # Use the username you created/wish to update
    database_name_to_manage = 'your_application_db' # The database name related to this user

    print(f"\nAttempting to update user '{user_to_update}'...")
    try:
        # Check if user exists before attempting update (update_user can raise error if not found)
        if not user_manager.has(user_to_update):
             print(f"User '{user_to_update}' not found. Cannot proceed with updates.")
        else:
            # --- Example Update Operations ---

            # Example: Change password (Uncomment to use with a new password)
            # new_pw = 'a_brand_new_secure_password_updated'
            # print(f"  Attempting to change password...")
            # try:
            #     user_manager.update_user(user_to_update, password=new_pw)
            #     print(f"  Password for user '{user_to_update}' changed.")
            # except Exception as e:
            #     print(f"  Failed to change password for '{user_to_update}': {e}")

            # Example: Change active status
            print(f"  Attempting to change active status...")
            try:
                user_manager.update_user(user_to_update, active=True) # Set user back to active
                print(f"  User '{user_to_update}' updated (set to active).")
                # To set as inactive: user_manager.update_user(user_to_update, active=False)
            except Exception as e:
                 print(f"  Failed to change active status for '{user_to_update}': {e}")


            # Example: Change database access (this *replaces* existing grants for listed databases, doesn't merge)
            # Grant read-only access to the system database and read/write to your application database
            print(f"  Attempting to update database access for user '{user_to_update}'...")
            try:
                # Ensure the target database exists before setting permissions for it
                if client.has_database(database_name_to_manage):
                     user_manager.update_user(
                          user_to_update,
                          databases={
                              '_system': 'ro', # Example: Grant read-only access to _system database
                              database_name_to_manage: 'rw' # Ensure this database exists, grant read/write access
                              # Add other databases and permissions as needed
                          }
                     )
                     print(f"  User '{user_to_update}' database access updated (ro on _system, rw on {database_name_to_manage}).")
                      # To revoke access to a specific database, update without including it in the dictionary.
                      # To revoke all database access, set databases={}
                else:
                     print(f"  Database '{database_name_to_manage}' not found. Cannot set permissions for it.")


            except Exception as e:
                 # This might fail if the user lacks privileges to grant access
                 print(f"  Failed to update database access for '{user_to_update}': {e}")

    except Exception as e:
         # This initial catch is less likely if has() check is done, but good practice
         print(f"\nAn unexpected error occurred during update operations for user '{user_to_update}': {e}")

else:
    print("\nNot connected to _system with sufficient privileges to update users.")

# Ensure user_manager object exists
if 'user_manager' in locals() and user_manager:
    user_to_delete = 'an_old_user_to_be_deleted' # REPLACE with the username you want to delete

    print(f"\nAttempting to delete user '{user_to_delete}'...")
    try:
        # Safety check: Prevent accidentally deleting critical users like 'root' or your primary app user
        if user_to_delete in ['root', 'your_app_user']: # Add other critical users as needed
             print(f"Deletion of critical user '{user_to_delete}' is prevented by script safety check.")
        elif not user_manager.has(user_to_delete): # Optional: Check if user exists first
            print(f"User '{user_to_delete}' not found. Nothing to delete.")
        else:
            user_manager.delete_user(user_to_delete)
            print(f"User '{user_to_delete}' deleted.")

    except Exception as e:
        # This might still catch errors if has() check is skipped or permissions are insufficient
        print(f"Failed to delete user '{user_to_delete}': {e}")
else:
    print("\nNot connected to _system with sufficient privileges to delete users.")

# Assuming your backup directory is /path/to/your/arangodb/backups on host
# and it exists and Docker user has permissions.
# We add a temporary volume mount just for this command execution.

# Options explained for arangodump:
# --server.endpoint=tcp://127.0.0.1:8529: Connect to the ArangoDB server from *inside* the container using localhost/port
# --server.database=your_application_db: Specify the database to back up (REPLACE with your database name)
# --server.username=root: User for authentication (root is easiest for management tasks like backup/restore)
# --server.password='your-secret-password': Password for the user (REPLACE with your root password set during docker run)
# --output-directory=/backup_data: Directory *inside the container* where backup will be written.
#                                  This will be the mount point for the host directory.

docker exec \
  -e ARANGO_ROOT_PASSWORD='your-secret-password' \
  -v /path/to/your/arangodb/backups:/backup_data \
  arangodb_instance \
  arangodump \
  --server.endpoint=tcp://127.0.0.1:8529 \
  --server.database=your_application_db \
  --server.username=root \
  --server.password='your-secret-password' \
  --output-directory=/backup_data

# Assuming your backup data is in /path/to/your/arangodb/backups on host.
# We mount this host directory as a temporary volume inside the container at /backup_data.

# Options explained for arangorestore:
# --server.endpoint=tcp://127.0.0.1:8529: Connect to the ArangoDB server
# --server.database=your_application_db: Specify the database to restore INTO.
#                                        If the DB exists, you might need to drop it first.
# --server.username=root: User for authentication
# --server.password='your-secret-password': Password for the user
# --input-directory=/backup_data: Directory *inside the container* containing the backup data
# --create-database true: Add this if restoring into a database that might not exist or was just dropped.

# Example: Restore into the *same* database name (requires dropping first if it exists)
# You might want to stop your application connecting to the DB before dropping/restoring.

# Optional: First, drop the existing database (BE CAREFUL! This ANGELES ALL DATA IN THAT DB!)
# Use arangosh inside the container to drop the database:
# docker exec \
#   -e ARANGO_ROOT_PASSWORD='your-secret-password' \
#   arangodb_instance \
#   arangosh \
#   --server.endpoint tcp://127.0.0.1:8529 \
#   --server.username root \
#   --server.password 'your-secret-password' \
#   --database _system \
#   --javascript.execute-string "db._dropDatabase('your_application_db');" # REPLACE with your database name

# Then, perform the restore:
docker exec \
  -e ARANGO_ROOT_PASSWORD='your-secret-password' \
  -v /path/to/your/arangodb/backups:/backup_data \
  arangodb_instance \
  arangorestore \
  --server.endpoint=tcp://127.0.0.1:8529 \
  --server.database=your_application_db \
  --server.username=root \
  --server.password='your-secret-password' \
  --input-directory=/backup_data \
  --create-database true # Use this if the DB was dropped or doesn't exist

# Run a temporary container on the same network as arangodb_instance,
# mount host backup volume, install arangodb tools via apk, and run arangodump.
# The container will automatically exit after the command finishes printing output.
# /bin/sh -c "..." allows executing multiple commands sequentially (install then dump).

docker run --rm \
  --network my_arangodb_network \
  -v /path/to/your/arangodb/backups:/backup_data \
  alpine \
  /bin/sh -c "apk update && apk add --no-cache arangodb \ # Update package list & Install arangodump/arangorestore
             && arangodump \
                --server.endpoint=tcp://arangodb_alias:8529 \ # Connect using the network alias to the running DB container
                --server.database=your_application_db \
                --server.username=root \
                --server.password='your-secret-password' \
                --output-directory=/backup_data" # Write backup to the mounted host directory

# Similar to backup, run a temporary container on the same network, install tools, and run arangorestore.

docker run --rm \
  --network my_arangodb_network \
  -v /path/to/your/arangodb/backups:/backup_data \
  alpine \
  /bin/sh -c "apk update && apk add --no-cache arangodb \
             && arangorestore \
                --server.endpoint=tcp://arangodb_alias:8529 \ # Connect using the network alias
                --server.database=your_application_db \ # Database to restore INTO
                --server.username=root \
                --server.password='your-secret-password' \
                --input-directory=/backup_data \ # Read backup from the mounted host directory
                --create-database true" # Add this if restoring into a database that might not exist

# Remember to handle existing database content as needed before restoring (e.g., drop it first).
# You can also use the arangosh command shown in the 'docker exec' restoration section to drop the DB.